Well here's my first attempt at summarising this thread. I've tried to pluck 
out the ideas that we can do right now (i.e. that don't depend on parser 
changes). I've selected what I think are the simplest of the ideas and built 
them into what I'd propose as a cohesive starting point.

Some of the discussion points covered ideas that I think fit better into 
'best practice' tutorials and guidance notes. I've set them aside for now, 
but I think we should probably host such tutorials/guidance on the web site. 
Some of the things that I've considered to be in this category include the 
idea to have one object per file, positioning objects at the origin and 'y' 
being 'up'.

Naming Conflicts
-----------------
I think the most important thing to address will be to avoid naming 
collisions for files and identifiers. The simplest way of doing this will be 
for contributions to adhere to naming standards based upon a name chosen by 
the contributor. The name should be indicative of the content or purpose of 
the contribution. Once a name has been chosen, no other contributions can 
bear the same name, although clearly a particular contribution could be 
changed almost beyond recognition over time by successive editors. Prefixes 
will need to be used for file and identifier names (macros, variables, 
functions etc).

The full contribution name could be used as the prefix. I think we should 
also permit a shortened code to be used, but this would also need to be 
unique.

Imagine someone creates a model of some cricket stumps and elects to name 
the contribution 'CricketStumps'. If they wish to make use of a short code 
and 'CS' has not already been used then they could register it. For this 
example though, lets assume that 'CS' has already been allocated so they end 
selecting 'CS2'.

Adherence to Naming Standards
---------------------------------
Use of the naming standards will be mandatory for contributions destined for 
inclusion in the 'standard' part of the collection. As part of the 
submission process the contributor will be required to indicate whether they 
consider they have adhered to the standards. The contribution initially goes 
into the 'ad-hoc' area. We could implement a 'feedback' screen where anyone 
could comment on a contribution, with an option to dispute that a 
contribution adheres to the standards.

If a contribution does adhere to the standards it could be promoted through 
into the 'standard' area. Otherwise it will remain in the 'ad-hoc' area. 
Such non-standard contributions would still be available for download, but 
would be clearly 'marked' by the server to warn people that they don't 
adhere to the standards (and to help prompt people to rectify the problem).

File Names
-----------
There's a limit on the number of directories we can declare in the library 
path, so downloaded #include files and accompanying files will normally need 
to go into just one directory - probably the include directory. Each of the 
files from the collection that is going to end up in this directory will 
therefore need to be uniquely named. Actually, I think that even if we use 
an alternative directory or multiple directories in some way the names would 
still need to be unique.

A contribution could contain multiple files, but all files in the 
contribution will need to be made unique by using a common designated 
prefix.

It probably be easiest to implement if the files all use the contribution 
name as a prefix. This would make it easier for automated routines on the 
server to manage parts of a contribution. The server could look for files 
called:
 o  CricketStumps.html - as the top-level documentation file for the 
contribution
 o  CricketStumps.keywords - for use with the search facility
 o  CricketStumps.pov - if present, could contain a simple renderable 
example of the object
 o  CricketStumps.inc - would be the main include file and could also be 
renderable
 o  CricketStumps.jpg - could contain a 800x600 render from which the server 
could generate a thumbnail.

Other files could be included in the contribution, so, if the contribution 
had its own separate texture file it could be called 
CricketStumps_Textures.inc. None of these files would be mandatory, but if 
not provided, the 'keywords' file would be created based on keywords entered 
into the upload page when the collection is submitted.

If we permit an abbreviated prefix to be used then file names could become 
CS2.inc, CS2_Textures.inc etc and the server would need to be able to 
recognise that they are part of the same contribution. Maybe we'd have a 
server generated file named CS2.CricketStumps to make the relationship 
between the name and the prefix clear to a user looking through their 
include directory.

If the contribution name needs to be followed by a descriptive name it 
should be separated using an underscore e.g. CS2_Textures.inc or 
CricketStumps_Textures.inc.

Does anyone know of any operating system of transfer software issues with 
mixed case letters that may make it more sensible to use all lowercase file 
names?

Identifier Names
----------------
In order that people will be able to use multiple contributions within a 
single POV scene, identifiers declared in the include files will need to be 
uniquely named so that they don't get mixed up with identifiers declared in 
other include files from the collection and with those used in the scene 
file.

The declaration of a variable intended to permit someone using the 
CricketStumps contribution to set a height for some stumps may therefore 
become '#declare CS2_StumpHeight = 0.85;'. Using an underscore here helps 
anyone who may need to rename a set of identifiers in the future, for 
example, anyone wishing to re-use a macro originally designed for 
positioning cricket stumps within a future contribution for creating a 
picket fence could readily rename identifiers.

Where an identifier does not need to be exposed to the person using the file 
it should be declared using the #local directive.

Macro and Function Names
----------------------------
Similarly Macro names and function names will need to be unique, and would 
need to be defined using the same unique prefix. e.g.

#macro CS2_CreateStumps (CS2_BailsOnFlag)
  ...
#end

Problematic File Types
-----------------------
It would be desirable to be able to permit non-SDL based utilities to be 
added to the collection, such as conversion utilities, but if executable 
files are permitted we should consider the potential question of viruses.

First step will be to check whether there's a virus scanner available to 
povray.org to enable automated scanning of submitted files.

Sizing Standards
----------------
There was a discussion about whether people should be required to use a 
standard size such as 1 POV-Ray unit = 1metre, but I think the consensus was 
that this would difficult to apply universally because very large scale 
(e.g. galaxies) and very small scales (atoms) can't reasonably adhere to 
such a standard. Furthermore, someone who is accustomed to working in 
Imperial measures could find it difficult to think in Metric.

I think the idea of documenting the units either in comments at the top of 
the file or in the accompanying documentation was the best and simplest 
idea. The contributor should also be encouraged to document the position and 
size of their object and to include a sample scene file that people can look 
at to easily work out how to get the object into the camera frame.

There was a proposal to have some generic unit conversion mechanism to allow 
contributors to use the units they find most appropriate, while enabling 
people to readily mix-and-match #include files.

This could be a macro or just some variable declarations and we could do 
both very easily. I see Charles has started off a macro. We could also 
create a standard #include file containing simple variable declarations 
using a standard naming format:

#declare inches2metres = 0.0254;
#declare inches2feet = 1/12;
#declare miles2kilometres = 1.609344;
#declare feet2metres = 0.3048;
#declare metres2inches = 39.37007874;
#declare feet2inches = 12;
#declare kilometres2miles = 0.621371192;
#declare metres2feet = 3.280839895;
#declare lightyear2parsec = 0.306391546;
#declare parsec2lightyear = 3.263797626 ;
... etc ...

Then, if an object was defined in metres and we wanted it in feet we'd just 
'scale metres2feet'.

We could even merge both ideas into a single include file, which could maybe 
even find its way into the standard POV-Ray includes directory with V3.7 or 
4.

Other Stuff
-----------
I'm sure that, over time, some clever people will develop utilities and 
techniques to help improve standardisation of contributions, for example, a 
parser to read a non-standard file and write out a standard one, ways of 
wrapping non-standard code to make it look standard and changes to the 
POV-Ray parser to introduce namespaces were all discussed.

If this all suits eveybody then I'd suggest that we plough ahead using an 
approach that's as straight forward as possible to get this off the ground 
and to see how it flies.

Anything I've missed, or that you disagree with?

Regards,
Chris B.

Post a reply to this message